/*
 * GroupState.java    0.0.1    21/dic/2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */ 
package org.mentalsmash.tazio.transparency.interfaces;

import java.util.HashMap;

import org.mentalsmash.tazio.commons.identifiers.NID;


/**
 * 
 * The <code>GroupState</code> interface has to be implemented by any object providing a 
 * shared group state.
 * <p>
 * As for now this interface is not used, it will be available in a further expansion to 
 * Tazio's functionalities. The main idea is to allow the ReplicaManagers to choose the 
 * less loaded server every time a Weak Replica Managers wants to connect, in order to 
 * balance the load throughout the whole group.
 * </p>
 * <p>
 * This above feature is not supported yet, because for testing purposes we chose to create 
 * a fully working system and test it as soon as we could and to add new features once the 
 * main system is completed.
 * </p>
 * 
 * @version 0.0.1	21/dic/2009
 * @author Enrico Savioli <savioli.enrico@gmail.com>
 */
public interface GroupState {

	/**
	 * The <code>clear()</code> resets the state to its original value, as if it had 
	 * never been updated.
	 *
	 */
	public void clear();
	
	/**
	 * The <code>update()</code> method updates the state of the group member identified 
	 * by the provided TazioNodeID.
	 * 
	 * @param id	the TazioNodeID of the member of the group whose state has to be updated.
	 */
	public void update(NID id);
	
	/**
	 * The <code>getNumberOfConnections()</code> method returns the number of WRMs 
	 * connected to the group member identified by the TazioNodeID passed as input parameter.
	 * 
	 * @param id	the TazioNodeID of the member whose number of connected WRMs has to 
	 * 				be retrieved.
	 * @return		the nember of WRMs connected to the group member identified by id.
	 */
	public int getNumberOfConnections(NID id);
	
	/**
	 * The <code>getSize()</code> method returns the length of the object representing 
	 * the state of the group.
	 * 
	 * @return	the length of the object representing the state of the group.
	 */
	public int getSize();
	
	/**
	 * The <code>getState()</code> is an implementation specific method used for 
	 * testing purposes. It returns the state represented as an HashMap object.
	 * 
	 * @return	the HashMap encapsulating the state of the group.
	 */
	public HashMap<NID, Integer> getState();
	
	/**
	 * The <code>getLessLoadedServer()</code> method analyses the state and returns 
	 * the TazioNodeId of the ReplicaManager with the lowest number of Weak Replica 
	 * Managers connected to it.
	 * 
	 * @return	the TazioNodeId of the RM with the lowest number of WRMs connected to it. 
	 */
	public NID getLessLoadedMember();
		
}
